Project-7525: [DO NOT MERGE] Feature branch for the new returns flow by bc-vivekaggarwal · Pull Request #2667 · bigcommerce/cornerstone

bc-vivekaggarwal · 2026-05-27T00:42:05Z

What?

This PR is for a feature branch to park all reviewed changes related to the new returns flow PROJECT-7525

Requirements

CHANGELOG.md entry added (required for code changes only)

Tickets / Documentation

PROJECT-7525

Screenshots (if appropriate)

Not applicable: They are part of individual PRs

Testing

TBD

Note

High Risk
Introduces new order-return GraphQL mutations and multi-page account/guest flows that merchants inherit; regressions affect real shoppers and return submission/cancellation behavior.

Overview
Adds the returns v2 shopper experience when settings.returns_v2_enabled is on: new create return, guest return portal, and return detail pages with matching theme JS (Storefront GraphQL for create, guest session start, and cancel), SCSS, and navigation/orders entry points gated alongside legacy returns_enabled.

The account returns list switches to a v2 layout (status badges, totals, cursor pagination, contextual “View details” links). Shared pieces include return-items-total, cursor-paginator, theme tokens for return status colors, and a large lang/en.json expansion.

Accessibility is woven through the new flows (landmarks, loop-safe ids, aria-labelledby for responsive labels, live regions, aria-disabled submit with hints, error/confirmation focus patterns) and documented in a new in-repo accessibility skill plus Cursor template-accessibility review rules. Smaller cross-cutting updates: alert modal dialog semantics, translatable <title> fallbacks for standalone return routes, legacy add-return table labeling, and optional “Go to return portal” on CMS pages.

^{Reviewed by Cursor Bugbot for commit 73581e4. Bugbot is set up for automated code reviews on this repo. Configure here.}

Copilot

Pull request overview

This PR parks initial Cornerstone theme changes for PROJECT-7525’s “new returns flow”, adding new templates/assets for a redesigned return-request experience and gating existing “Return” affordances on a new settings.returns_v2_enabled flag (with fallback to settings.returns_enabled).

Changes:

Add new return-related templates: a guest return portal page and a new account “add return” page layout.
Add new styling and a new page manager (AddReturnNew) plus bundle wiring for the new return-request UI.
Gate “Return” entry points in order details and orders list on returns settings; update CHANGELOG.md.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
templates/pages/guest-return-portal.html	New guest-facing return portal page scaffold.
templates/pages/account/orders/details.html	Gate “Return” button using `returns_v2_enabled` OR `returns_enabled`.
templates/pages/account/add-return-new.html	New account return-request page markup for the redesigned flow.
templates/components/account/orders-list.html	Gate “Return Items” link using `returns_v2_enabled` OR `returns_enabled`.
CHANGELOG.md	Add draft entries for the new return pages / gating changes.
assets/scss/components/stencil/addReturn/_addReturn.scss	Add styling for the new return-request page (`.newReturn`).
assets/js/theme/add-return-new.js	New page manager that renders the new return UI (currently with placeholder data).
assets/js/app.js	Wire `account_new_return` page type to load the new return page manager.

Comments suppressed due to low confidence (3)

assets/js/theme/add-return-new.js:96

Date formatting is hardcoded to the en-AU locale. This will display incorrect date formats for stores with different locales; use store locale from Stencil context (e.g. this.context.storeLocale) or omit the locale to allow the browser/store locale to drive formatting.

            // TODO ORDERS-7715: invoke createReturn Storefront GQL mutation.
        });
    }
}

assets/js/theme/add-return-new.js:142

Currency formatting is hardcoded to en-AU and always uses item.totalIncTax even though order.isTaxInclusive is available. This will display incorrect amounts/formatting for non-AU stores and for tax-exclusive display settings. Use a locale from context and choose totalIncTax vs totalExTax based on order.isTaxInclusive (or use server-provided formatted totals if available).
assets/js/theme/add-return-new.js:239
console.log('Submitting return', ...) should not ship in theme code. Either remove it or gate it behind an explicit debug flag, and replace with the real API call / proper error handling when wiring this up.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

    account_order: getAccount,
    account_addressbook: getAccount,
    shippingaddressform: getAccount,
-    account_new_return: getAccount,
+    account_new_return: getAddReturnNew,
    'add-wishlist': () => import('./theme/wishlist'),


+{{> components/common/breadcrumbs breadcrumbs=breadcrumbs}}
+
+<h1> Guest Return Portal</h1>
+


+        </div>
+        <div class="newReturn-headerActions">
+            <a href="{{../urls.account.orders.all}}" class="newReturn-btnBack">{{lang 'account.orders.return.back_button'}}</a>
+            <a href="/return-policy" class="newReturn-btnPolicy">View return policy &rarr;</a>
+        </div>
+    </div>
+    {{#if date}}<p class="newReturn-orderDate">{{date}}</p>{{/if}}


+        this.bindSubmit($form);
+    }
+
+    bindOrderLineItemEvents() {
+        document.querySelectorAll('.newReturn-stepperBtn').forEach(button => {
+            button.addEventListener('click', () => {
+                // Derive itemId from the parent row — buttons do not carry data-item-id,
+                // so the [data-item-id] selector stays scoped to the row container only.
+                const row = button.closest('.newReturn-orderLineItem');
+                const itemId = row?.dataset?.itemId;
+                if (!itemId) return;
+                const action = button.getAttribute('data-action');


 - Fix duplicate `id="default_instrument"` on Update Payment Method page [#2661](https://github.com/bigcommerce/cornerstone/pull/2661)
 - Respect `available_to_sell` on PDP so the Sold Out alert is hidden and the Add to Cart button stays enabled for backorderable products, and is disabled when quantity exceeds `available_to_sell` [#2659](https://github.com/bigcommerce/cornerstone/pull/2659)
 - Updated accessibility features [2656](https://github.com/bigcommerce/cornerstone/pull/2656)
+- Adds new guest-return-portal page. [2645](https://github.com/bigcommerce/cornerstone/pull/2645)


denis-bc · 2026-05-28T01:47:53Z

cursor review

cursor · 2026-07-15T23:59:10Z

+    }
+
+    startReturnGuestSession(input) {
+        return fetch('/graphql', {


GraphQL fetch omits base URL

Medium Severity

New returns flows call fetch('/graphql', …) with a root-absolute URL, unlike other theme API usage that passes secureBaseUrl, so GraphQL may miss the correct prefixed path on multi-language storefronts.

Additional Locations (1)

assets/js/theme/create-return.js#L92-L93

^{Reviewed by Cursor Bugbot for commit 99a9c87. Configure here.}

cursor · 2026-07-23T23:41:04Z

+            const overlay = document.querySelector('.guest-return-portal .loadingOverlay');
+            if (submitBtn) submitBtn.disabled = true;
+            if (overlay) overlay.style.display = 'block';
+            const payload = this.buildRequestPayload();


Guest error alert never cleared

Low Severity

The guest return portal shows errors via showError but never hides or clears the alert when a new submit starts. A prior failure message stays visible during and after later attempts until navigation succeeds.

^{Reviewed by Cursor Bugbot for commit 8447deb. Configure here.}

cursor · 2026-07-23T23:42:20Z

+                    throw new Error('Failed to start return guest session');
+                }
+
+                window.location.href = `/create-return/${payload.orderEntityId}`;


Root-absolute return URLs

Medium Severity

After a successful guest session, navigation uses a root-absolute /create-return/... URL, and the returns list links to /account.php?.... On multi-language storefronts with locale subfolders, those paths skip the active prefix while other return links use urls.*, so shoppers can land on the wrong locale or a broken page.

Additional Locations (1)

templates/components/account/returns-list-v2.html#L18-L19

^{Reviewed by Cursor Bugbot for commit de1a079. Configure here.}

… on returns details page (#2697) * feat(returns): ORDERS-7900: strike requested with resolved resolution on returns details page * feat(returns): ORDERS-7900: add translation strings for resolution request

…page for desktop/tablet/mobile views

…creating a return

…return detail page

…v2 returns (#2714)

…2713)

…rebase

)

feat(orders): ORDERS-7706 add new return page layout

…atus badge

…ake_case context

…try-point links

…wice

…r accessibility and seo (#2726) * feat(returns): ORDERS-7945 add page title to returns related pages for accessibility and seo * feat(returns): ORDERS-7945 add page title to create returns and guest return portal pages only

…ng pages

…based on context flag (#2731)

…returns listing and details page

bc-vivekaggarwal requested review from BC-SEven, bc-bryan, denis-bc, jpajar and matt-evangelidis May 27, 2026 00:42

bc-vivekaggarwal requested a review from a team as a code owner May 27, 2026 00:42

denis-bc requested a review from Copilot May 27, 2026 00:50

BC-SEven added the do not merge label May 27, 2026

BC-SEven changed the title ~~Project-7525: Feature branch for the new returns flow~~ Project-7525: [DO NOT MERGE] Feature branch for the new returns flow May 27, 2026

Copilot started reviewing on behalf of denis-bc May 27, 2026 01:00 View session

denis-bc requested review from Copilot and removed request for Copilot May 27, 2026 03:33

Copilot started reviewing on behalf of denis-bc May 27, 2026 03:33 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

cursor Bot reviewed May 28, 2026

View reviewed changes

Comment thread assets/js/app.js Outdated

cursor Bot reviewed Jun 2, 2026

View reviewed changes

Comment thread assets/js/theme/add-return-new.js Outdated

cursor Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread templates/pages/account/add-return.html Outdated

cursor Bot reviewed Jun 17, 2026

View reviewed changes

Comment thread templates/pages/create-return.html Outdated

Comment thread assets/js/theme/create-return.js

cursor Bot reviewed Jun 23, 2026

View reviewed changes

Comment thread assets/js/theme/create-return.js

Comment thread assets/js/theme/create-return.js

Comment thread assets/js/theme/create-return.js

Comment thread templates/pages/create-return.html

cursor Bot reviewed Jun 23, 2026

View reviewed changes

Comment thread templates/components/account/returns-list-v2.html Outdated

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread templates/components/account/returns-list-v2.html Outdated

Comment thread templates/pages/account/return-details.html

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread assets/js/theme/create-return.js

BC-SEven force-pushed the feature/PROJECT-7525-new-returns-flow branch from 34bc18e to 38101ea Compare July 1, 2026 01:09

cursor Bot reviewed Jul 2, 2026

View reviewed changes

Comment thread assets/js/theme/return-details.js

cursor Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread assets/js/theme/guest-return-portal.js

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread assets/js/theme/create-return.js

Comment thread templates/pages/create-return.html

cursor Bot reviewed Jul 15, 2026

View reviewed changes

cursor Bot reviewed Jul 23, 2026

View reviewed changes

bc-vivekaggarwal and others added 29 commits September 3, 2026 09:39

feat(returns): ORDERS-7900: strike requested with resolved resolution…

3b5a20e

… on returns details page (#2697) * feat(returns): ORDERS-7900: strike requested with resolved resolution on returns details page * feat(returns): ORDERS-7900: add translation strings for resolution request

feat(returns): ORDERS-7752 add cursor pagination to returns

29099b0

feat(returns): ORDERS-7752 use pagination.<resource> key

fad6436

feat(returns): ORDERS-7752 use div with region role

d3672e6

feat(orders): ORDERS-7770 add responsive styling for returns details …

328441b

…page for desktop/tablet/mobile views

feat(orders): ORDERS-7837 add additional note field to mutation when …

ea1a9c1

…creating a return

feat(orders): ORDERS-7838 add additional note section to new shopper …

bcff912

…return detail page

feat(orders): ORDERS-7647 update return list navigation to work with …

21784af

…v2 returns (#2714)

feat(orders): ORDERS-7890 add product images to return details page (#…

d766d4f

…2713)

chore(common): PROJECT-7525 move CHANGELOG items back to draft after …

7594a5d

…rebase

feat(returns): ORDER-7874 add accessibility to create return page (#2712

5f6346f

)

Merge pull request #2649 from bigcommerce/ORDERS-7706

87db9d5

feat(orders): ORDERS-7706 add new return page layout

Merge pull request #2649 from bigcommerce/ORDERS-7706

1602d12

feat(orders): ORDERS-7706 add new return page layout

fix(returns): ORDERS-7752 rename keys to be snake_case for consistency

60fb8b7

feat(returns): ORDERS-7878 add accessibility to returns list page

8420d34

chore(other): add Bugbot config

7b994a9

feat(orders): ORDERS-7961 fix styling for Warm and Bold themes for St…

426f0cf

…atus badge

fix(returns): ORDERS-7719 align return detail page with design and sn…

2242da5

…ake_case context

feat(returns): ORDERS-7875 add accessibility to return detail page

30b719f

feat(returns): ORDERS-7877 add order-scoped aria-labels to returns en…

ff453fd

…try-point links

feat(orders): ORDERS-7876 improve accessibility for guest-return page

bc4cc2f

feat(orders): ORDERS-7876 clear errors to prevent announcing errors t…

7442d25

…wice

feat(orders): ORDERS-7966 add items total to returns detail and listi…

21bcea7

…ng pages

feat(orders): ORDERS-7966 rename labels as per feedback

91912e6

feat(orders): ORDERS-7959 add "go to return portal link" in webpages …

46f64aa

…based on context flag (#2731)

feat(orders): ORDERS-7965 fix return listing page quantity displayed

3460616

feat(orders): ORDERS-7965 align date format and status badge between …

fd3eba7

…returns listing and details page

feat(orders): ORDERS-7965 add total for each line item in a return

73581e4

BC-SEven force-pushed the feature/PROJECT-7525-new-returns-flow branch from 0bee8f0 to 73581e4 Compare September 2, 2026 23:41

		{{> components/common/breadcrumbs breadcrumbs=breadcrumbs}}

		<h1> Guest Return Portal</h1>

Uh oh!

Conversation

bc-vivekaggarwal commented May 27, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Requirements

Tickets / Documentation

Screenshots (if appropriate)

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

denis-bc commented May 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot Jul 15, 2026

Choose a reason for hiding this comment

GraphQL fetch omits base URL

Uh oh!

cursor Bot Jul 23, 2026

Choose a reason for hiding this comment

Guest error alert never cleared

Uh oh!

cursor Bot Jul 23, 2026

Choose a reason for hiding this comment

Root-absolute return URLs

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bc-vivekaggarwal commented May 27, 2026 •

edited by cursor Bot

Loading